VGIS Application Server Listeners
=================================

This directory contains the executables and source files for the VGIS
sample processing listeners. The three listeners run from this directory, 
responding to requests received on Oracle pipes. 

The three listeners are: the message listener, responsible for receiving 
messages from a pipe and saving them to the process_transactions and 
process_messages table; the server_state listener that responds to requests
regarding the set of processing running and information on a specific
process; and the process listener which initiates the processing of 
transactions initiated either from the creation of a process_transaction 
record or by a data file arriving in a remote ftp directory, as well the
process listener is responsible for notifying users by e-mail the results
of sample processing. 


Execution Instructions
======================

In order for the listeners to e executed, the required environment
variables must be set. Currently a script '.env' is called within the 
executing users profile to set the following variables:
	APP_USER     e.g. APP_USER=vgis
	APP_PSWD     e.g. APP_PSWD=password
	VEG_APP_HOME e.g. VEG_APP_HOME=/home/cwatmoug/listeners
	FTP_HOME     e.g. FTP_HOME=/apps_ux/vgis/delivery/vegbat1/ftp

The listeners can be started from within the listeners directory by
executing the script 'start_listeners.sh'.

Note: there is a requirement for the $USER variable to be set. In some
circumstances is the 'su' command has been used, that variable is not 
set and the listeners will not function correctly. 


Modules
=======

check_dir.sh  - This script is used by the process listener to retrieve a 
                directory listing of the remote ftp directory. 
                The shell script connects to the remote ftp server and 
                produces a listing of the files found there. The script 
                expects the following parameters: 
		  1) the ftp server e.g. ftp.gov.bc.ca
		  2) the username for the ftp server account
		  3) the password for the ftp server account
		  4) the directory containing the datafiles 

get_file.sh   - This script is used by the process listener to retrieve a 
                specified file from the remote ftp directory. 
                The shell script connects to the remote ftp server and 
                retrieves the specified file, then moves it to the Processed
                directory. The script expects the following parameters: 
		  1) the ftp server e.g. ftp.gov.bc.ca
		  2) the username for the ftp server account
		  3) the password for the ftp server account
		  4) the directory containing the datafile 
		  5) the datafile filename 

msglog_listener.sh - This shell script executes in SQL*Plus, the PL/SQL block 
                in msglsnr.sql that listens for messages on the MESSAGE pipe. 
		Messages received are written to the PROCESS_MESSAGE and 
		ORACLE_ERROR_MESSAGES table in the database. The script expects
		the environment variables $APP_USER, $APP_PSWD and 
                $VEG_APP_HOME to be set


msglsnr.sql  - 	This SQl*Plus script is the Process essage listener that 
		pulls message from the message pipe, placed on by the VGIS 
                application, and stores them to the PROCESS_MESSAGES table. 
		The script is halted by sending it a message containing 
		'SHUTDOWN' which will cause it to halt. 

pipemgr.sql - 	Oracle DBMS Pipe code example from Oracle.

pipmgr_listener.sh - Pipe Manager listener that executes the pipmgr.sql sample
		listener script. 

process_listener.pc - The listener that provides the majority of the offline
		execution in VGIS. This listener is responsible for executing 
		any tasks requested by entries in the PROCESS_TRANSACTIONS 
		tables, notifying people based on the result of data 
		validations and uploads, and checking the remote FTP server for
		the arrival of files and then loading, validating and uploading
		the data from the files. This deamon also communicates with the
		server_state listener to determine the CPU time used for each
		process.
		
process_server.sh - script that executes the process_listener. The script 
		expects the environment variables $APP_USER, $APP_PSWD and 
                $VEG_APP_HOME, and $USER to be set.

server_state.pc - this listener waits on the pipe named SERVER_STATE and 
                supports requests for information regarding: the set of running
                processes; the state of the server and the other listeners; 
		a summary of the samples that have been loaded into 
                the database; and the amount of CPU time an individual
		process has accumulated. 

server_state.sh - script that executes the server_state listener. The script 
		expects the environment variables $APP_USER, $APP_PSWD and 
                $VEG_APP_HOME, and $USER to be set.

start_listeners.sh - the script that starts the server_state listener, the 
		msglog_listener and the process_server listener. The listener 
		daemons are started with the 'at' command to be run immediately
		by the cron daemon. 

stop_listeners.sh - script to stop the message listener, process listener and
		the server state listener. Since all three of these listeners
		operate by listening on a pipe, the shutdown script simply send
		seach of the processes a SHUTDOWN message as a request to halt.
		If the script is executed multiple times, the shutdown requests
		will build up on the pipe so each listener is responsible for 
		discarding any extra shutdown messages on startup.


Environment Variables Required
==============================

$APP_USER 

$APP_PSWD 

$USER

$VEG_APP_HOME 



Compilation
===========

Re-compile the Pro*C modules server_state dn process_listener with the 
following command:

	rm process_listener
	rm server_state
	make all

In addition, each of the modules can be compiled separately with

	rm process_listener
	make server_state 
or
	rm server_state
	make process_listener


The makefile will compile server_state as follows:

	server_state.pc -> server_state.c -> server_state.o -> server_state

The makefile will compile process_listener as follows:

	process_listener.pc -> process_listener.c -> process_listener.o 
		-> process_listener

If make insists that either server_state or process_listener is already up to 
date, you can mark the source as changed as follows:

	touch server_state.pc
or
	touch process_listener.pc

Overall, the only required pieces for the modules is server_state.pc and
process_listener.pc since the rest are derived.



Run-Time Error Tracing - core dumps
===================================

If the program core dumps,  the core file can be used to trace the exact 
location in the code where the abend occurred. Using the core file and
an exact copy of the executable that generated the core enter the following
commands:

	dbx server_state core

	where

'dbx' will indicate the line in server_state.c where the error occured. Examine
the error points in server_state.c taking note of their location in reference
to the rest of the code but do not change server_state.c since it is generated!
(very easy to forget and lose the changes) Make the corresponding changes to 
server_state.pc and re-compile.